.
.TH LLAPI_HSM_COPYTOOL_REGISTER 3 "2014-09-24" "" "Lustre HSM User API"
.SH NAME
llapi_hsm_copytool_register \- Lustre API copytool management
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fB#include <lustre/lustreapi.h>\fP
.sp
\fBint llapi_hsm_copytool_register(struct hsm_copytool_private **\fPpriv\fB,
const char *\fPmnt\fB, int\fP archive_count\fB, int *\fParchives\fB,
int\fP rfd_flags\fB)\fP
.sp
\fBint llapi_hsm_copytool_unregister(struct hsm_copytool_private **\fPpriv
\fB)\fP
.sp
\fBint llapi_hsm_copytool_get_fd(struct hsm_copytool_private *\fPct\fB)\fP
.sp
\fBint llapi_hsm_copytool_recv(struct hsm_copytool_private *\fPpriv\fB,
**struct hsm_action_list **\fPhal\fB, int *\fPmsgsize\fB)\fP
.sp
\fBstruct hsm_action_item *hai_first(struct hsm_action_list *\fPhal\fB)\fP
.sp
\fBstruct hsm_action_item *hai_next(struct hsm_action_item *\fPhai\fB)\fP
.SH DESCRIPTION
.sp
To receive HSM requests from a Lustre filesystem, a copytool
application must register with Lustre by calling
\fBllapi_hsm_copytool_register\fP(). The mountpoint of the Lustre
filesystem to monitor is indicated by \fImnt\fP\&. \fIarchives\fP is an array
with up to 32 elements indicating which archive IDs to register
for. Each element is a number from 1 to 32. \fIarchive_count\fP is the
number of valid elements in the \fIarchive\fP array. If an element in
\fIarchives\fP is 0, or if \fIarchive_count\fP is 0, then all archives will be
monitored. \fIrfd_flags\fP determines whether \fBllapi_hsm_copytool_recv\fP
will be blocking, with 0, or non\-blocking, with O_NONBLOCK.
.sp
\fBllapi_hsm_copytool_register\fP returns \fIpriv\fP, an opaque
pointer that must be used with the other functions.
.sp
\fBllapi_hsm_copytool_unregister\fP unregisters a copytool. \fIpriv\fP is
the opaque handle returned by \fBllapi_hsm_copytool_register\fP\&.
.sp
\fBllapi_hsm_copytool_get_fd\fP returns the file descriptor used by the
library to communicate with the kernel. This descriptor is only
intended to be used with \fBselect(2)\fP or \fBpoll(2)\fP\&. \fIrfd_flags\fP
should have been set to O_NONBLOCK.
.sp
To receive the requests, the application has to call
\fBllapi_hsm_copytool_recv\fP\&. When it returns 0, a message is available
in \fIhal\fP, and its size in bytes is returned in \fImsgsize\fP\&. \fIhal\fP points
to a buffer allocated by the Lustre library. It contains one or more
HSM requests. This buffer is valid until the next call to
\fBllapi_hsm_copytool_recv\fP\&.
.sp
\fIhal\fP is composed of a header of type \fIstruct hsm_action_list\fP
followed by one or several HSM requests of type \fIstruct
hsm_action_item\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct hsm_action_list {
   __u32 hal_version;
   __u32 hal_count;         /* number of hai\(aqs to follow */
   __u64 hal_compound_id;   /* obsolete and may be ignored */
   __u64 hal_flags;
   __u32 hal_archive_id;    /* which archive backend */
   __u32 padding1;
   char hal_fsname[0];      /* null\-terminated name of filesystem */
};

struct hsm_action_item {
    __u32      hai_len;     /* valid size of this struct */
    __u32      hai_action;  /* hsm_copytool_action, but use known size */
    struct lu_fid hai_fid;     /* Lustre FID to operated on */
    struct lu_fid hai_dfid;    /* fid used for data access */
    struct hsm_extent hai_extent;  /* byte range to operate on */
    __u64      hai_cookie;  /* action cookie from coordinator */
    __u64      hai_gid;     /* grouplock id */
    char       hai_data[0]; /* variable length */
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To iterate through the requests, use \fBhai_first\fP to get the first
request, then \fBhai_next\fP\&.
.SH RETURN VALUE
.sp
\fBllapi_hsm_copytool_register\fP and \fBllapi_hsm_copytool_unregister\fP
return 0 on success. On error, a negative errno is returned.
.INDENT 0.0
.TP
.B \fBllapi_hsm_copytool_get_fd\fP returns the file descriptor associated
with the register copytool. On error, a negative errno is returned.
.UNINDENT
.sp
\fBllapi_hsm_copytool_recv\fP returns 0 when a message is available. If
the copytool was set to non\-blocking operation, \-EAGAIN is
immediately returned if no message is available. On error, a negative
errno is returned.
.SH ERRORS
.INDENT 0.0
.TP
.B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
registered, ...
.UNINDENT
.sp
\fB\-ESHUTDOWN\fP The transport endpoint shutdown.
.sp
\fB\-EPROTO\fP Lustre protocol error.
.sp
\fB\-EAGAIN\fP No HSM message is available, and the copytool was set
to not block on receives.
.SH SEE ALSO
.sp
\fBllapi_hsm_action_begin\fP(3), \fBllapi_hsm_action_end\fP(3),
\fBllapi_hsm_action_progress\fP(3), \fBllapi_hsm_action_get_dfid\fP(3),
\fBllapi_hsm_action_get_fd\fP(3), \fBlustreapi\fP(7)
.sp
See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this
API.
.SH AUTHOR
Frank Zago
.
